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1. INTRODUCTION 


The Kernel Manager is one of the low level system components comprising the PMX driver. 
It is intended to provide a mostly operating system independent layer with which to access 
various features of the hardware. It is responsible for device initialisation, memory 
allocation, interrupt handling, and power management. This document defines the interface 
to the various functions provided by the Kernel manager. 


2. WHAT THE KERNEL MANAGER IS 


¢& The Kernel Manager is a low level system component. This means that it runs as a VxD in 
Win9X, and as a Kernel-mode driver in Windows NT™. 


3. BUILDING THE KERNEL MANAGER 


You can build the Kernel Manager from either the nt4 or the win9x dierctory using the 
respective make files. Various options are supported: 


DEBUG=1 does a debug build 
NO_HOST_CBUFF=1 puts the CCB on the host, rather than in AGP memory 


SIM=1 does a build suitable for running simulations with simstim. Simulates a single 
PMXIC. 


s SIM_S3=1 does a build suitable for running the PMX software emulated drivers on an S3 
card. 


PMXLC=1 if used in combination with SIM=1 makes the simulated device a PMXLC rather 
than a PMXIC. It is now used to distinguish a PMXLC/PMX2 build from a PMX1C build. 


On a SIM=1 build, the Kernel Manager simulates a device with 4Mbytes of frame buffer, and 
no texture heap. By creating a registry key in HKEY LOCAL MACHINE called PMXSIM, 
you can vary the amount of texture heap. Simply set the entry SimTextureMemorySize to the 
size (in hex) of the texture heap you wish to simulate. 


You can also set the simulated physical frame buffer base by setting the the entry 
SimPhysicalBase, again in PMXSIM. 
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4. COMMUNICATING WITH THE KERNEL MANAGER 


The Kernel manager provides two interfaces to the same set of functions, to enable it to be 
called from both ring 3 (not supported on NT) and ring 0. The ring 3 interface allows access 
using a DevicelOControl call. The ring 0 interface is accessed by calling a VxD service (on 
Win9X), or an IOCTL (on NT), which returns a table of function pointers, which you can 
then call as you desire. 


The declaration of the Kernel Manager interface functions and #defines is available in the file 
kmapi.h. 


5. BASIC CONCEPTS 


5.1 Connecting with a device 


The first thing you need to do is to get the Kernel Manager’s function table. This is 
accomplished by : 


on Win9X : call the DIOCGetServiceTable function 
on WINNT : issuea KM IOCTL_GET SERVICE TABLE IOCTL. 


These will return a pointer to a table of functions (of type KM SERVICE TABLE), which 
can then be called directly (from ring 0). 


You can use the KMMapOSDevCookieToDevice function to obtain a PDPEVICE_CTLBLK 
given a windows DEV_NODE. Use dnOsDevCookie = 1 to get at a simulated device. The 
returned PDEVICE_CTLBLK acts as a handle to a particular PMX device. From the client’s 
point of view it acts purely as a unique identifier for a device, with no internal structure. If 
you are debugging through the Kernel Manager, the internal structure of a 
PDEVICE CTLBLK can be accessed by including kminc.h instead of kmapi.h. 


5.2 Errors 


Most Kernel Manager functions return an error code. You should test this after every call 
and take appropriate action if a faliure code is returned. Kmapi.h defines a large set of error 
codes, but the most important one is KM_OK, which indicates success. 


5.3 Threads And Code Loading 


The PMX primary core supports several threads (the exact number varies depending on the 
chip revision). Each of these threads has different hardware capabilities. You can find what 
thread has what capabilities by calling KMFindThreadWithCaps, setting the bits in the 
dwCaps field of the FIND THREAD structure according to the capabilities you desire, and 
the device you want to interrogate. 


Typical capabilities are: 
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KM HCAPS BG 
KM HCAPS DACCORE 


The function will set the dwThreadNum field of the structure to be a unique identifier for a 
thread possesing the desired capabilities. If no valid thread can be found, the function will 
return an error code != KM _ OK. 


Once you’ve acquired a thread number, you can load code onto that thread. This is simply 
achieved by calling KMLoadCodeFragment, setting the psDeviceCtlBlk field to the unique 
identifier for the PMX device you require, and the dwThread field to the number returned 
form KMFindThreadWithCaps. You also need to setup the pdwlinfoBuffer field to point to 
an area of memory holding the binary image of a .pce file containing the code fragment you 
want to load. 


5.4 Symbols 


A primary core code fragment can export symbol addresses to the external world by using the 
assembler directive EXPORT <label>. When the code is loaded, the Kernel Manager records 
the address of this label in a table, which can be queried using the KMGetSymbolAddress 
function. Both linear (host) and physical addresses can be obtained for any exported symbol. 


A code fragment may also contain a table called an API table within it. This is just an array 
of exported symbols. This table can be retrieved after a fragment has been loaded by calling 
the KMGetAPITable function. The table contains the physical addresses of the 
corresponding labels in the code after it has been loaded. 


5.5 Memory Allocation 


The Kernel Manager provides functions to allocate memory from the host’s shared arena, and 
from any card’s frame buffer. 


5.5.1 Frame Buffer Allocation 


The Kernel Manager creates several distinct heaps in the frame buffer at initialization time. 
Any of these heaps can be allocated from using either a static or a moveable allocation. A 
static allocated block has its location fixed for as long as it exists. A moveable allocated 
block can be moved by the memory manager whenever it wants to reduce fragmentation. 
Moveable blocks can be locked to prevent the memory manager from moving them. 


The heaps created in the frame buffer are :- 
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KM_ FB GENERAL HEAP -- holds primary core code, primary surface etc. 

KM _ FB PROTECT HEAP -- holds the asynchronous command interfaces (see below) 
KM_FB_ICACHE2 HEAP -- holds real-time code (1K maximum) 

KM_FB_ TEXTURE _ HEAP -- holds 3D textures 


Allocations can be made on any alignment that is a power of two greater than or equal to 8. 
Similarly you can choose not to split small allocations across page boundaries by setting the 
KM HEAP NOT SPLIT PAGE flag. See the reference section for KMAlIlocStaticFBMem 
and KMAllocMoveableFBMem for details. 


5.5.2 Host Allocation 


All host allocations are satisfied from shared memory. You can allocate from one of three 
heaps using the single function KMAllocHostMem 


KM HOST PAGEABLE_ HEAP 
KM HOST NON PAGEABLE_HEAP 


KM_ HOST NON CACHED HEAP (turns off caching by writing to the relevent PTE’s in 
the processor. Access to this memory is very slow — you are better off using AGP GART 
memory). 


There is also an API for allocating memory which is cache coherent with the primary core, 


€ see 


KMAlIlocHostCacheCoherentHeap for details. 


5.6 Asynchronous and Synchronous commands 


You can call routines on the primary core using a mechanism similar a remote procedure call. 
This is accomplished either by writing into the circular command buffer, or by using an 
asynchronous command interface. 


5.6.1 Asynchronous commands 


In order to use an asynchronous command, you first call KMAllocComlF to allocate a 
structure called a command interface. This contains a dwExeAddr which is (physical) address 
* of the primary core routine to excecute. It also contains an array of eight DWORDs, 
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adwUserData, which hold data to be passed to the asynchronous command. This data is 
accessible using the PARAMS register in the primary core code. 


Writing into these fields must be ordered so that adwUserData is filled out before 
dwExeAddr (a FENCED_WRITE macro provided in kmapi.h is suitable for enforcing this 
ordering). 


Having filled out these fields, you must then perform 
*(psCommandInterface->pdwKickerAddr) = 0x8001 


This informs the hardware that it has a new command to execute, by writing to the relevent 
‘kicker register’ for the thread. 


The command interface can be reused to send more than one command, but you must wait 
until the last command is complete before sending a second command with the same 
command interface. 


Asynchronous commands excecute as soon as possible, and may excecute out of order. 


The commands interface can be freed after use by calling KMFreeComlF. 


5.6.2 Synchronous commands 


Most commands to the primary core (blts for example) are synchronous commands. All 
synchronous commands are guarenteed to excecute in strict sequence (although an 
asynchronous command can interrupt this sequence at any time). A syncronous command is 
called by writing a command packet into a cyclic buffer called the circular command buffer. 


5.6.3 The circular buffer. 


This is a region of memory with 64K of active data space, and a 4K overflow buffer. Two 
global cursors into this region are maintained, a read Offset (Roff) and a write offset (Woff). 
These cursors live on the cache coherent region of the host (although the primary core will 
keep a local copy of the read offset, and update the host version now and again to maintain 
coherence). The primary core iterates around the CCB, calling the commands embedded 
therein in sequence. 


Command packets contain a primary core exe address field and a command size field 
(measured in bytes), at the head of their data. Because of certain hardware limitations, a 
command packet must be a multiple of 64 bytes in size. 


The sequence for performing a writing a command into the circular command buffer is: 
1) Exchange 1 with the dwAccess field of the circular command buffer 
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2) repeat until the result of the exchange is 0 
3) Call GET _PCCCB_ SPACE (a macro in kmapi.h) 


4) If there is insufficient space then wait or split the command 


5) If your command may be > 4K then you must test to make sure that Woff + 
CommandSize < 68K. If its not then you must split the command into 4K chunks. (or you 
could write a dummy command to wrap around etc.) 


6) Write the command into the buffer at the Write offset. 


7) Call the UPDATE PCCB_ WOFF(CommandSize) macro (which does Woff = (Woff + 
CommandSize) & 65535) 


* 8) Hit the kicker register for the BGO thread. (write a 1 into it) 


9) Write a zero into the dwAccess field of the circular command buffer 


Commands may be agglomerated together by writing them all at once, but you must 
remember to make sure that they meet the 4K condition 5). You must also write the number 
of agglomerated commands into the kicker register, rather than just a 1. 


There are two special commands: 
NoCmd: 


NO-OP command handler. The size field is used to tell the primary core how much to update 
& its read pointer by. 


Status: 


This allows us to determine the completion status of the preceding commands. It takes three 
parameters: the address to write to and the value to write when the preceeding operations 
complete. It also takes a flag indicating whether or not we should flush any pipelines after the 
blt. [You'd have to set this if you are using the status command as a synchronization point 
rather than indicating the ability to reuse a cache entry]. 


You can get obtain the dwAccess, Roff, and Woff pointers, as well as the linear base of the 
CCB by calling KMGetCmndBufferlInfo. The Roff and Woff pointers can be set by calling 
KMSetCmndBufferInfo. 
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5.7 Interrupts 


tbd 


5.8 State And Power Mode Changes 


A state change occurs when a particular device goes into or out of a full-screen DOS mode, 
or changes its power mode. 


You can register a callback function with the KM. This will be called both pre and post mode 
= change & power down. 


The callback function should be of the form: 


Fn( PDEVICE CTLBLK _ psDeviceCtlIBlk, DWORD ~ dwStateFlags, . DWORD 
dwContextLossSeverityFlags ) 


where dwStateF lags indicates the type of the message :- 


PMX PRE WINDOWS MODE CHANGE 
PMX PRE HIREZ TO VGA 

PMX POST HIREZ TO VGA 

PMX PRE VGA_TO_ HIREZ 

PMX POST VGA_TO_HIREZ 


PMX PRE XY REZ CHANGE 
PMX_POST_ XY REZ CHANGE 
PMX PRE Z REZ CHANGE 
PMX POST _Z REZ CHANGE 


PMX PRE POW STATEO 

PMX POST POW _STATEO 

PMX _PRE POW STATE1 
6 PMX POST POW STATE1 
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PMX PRE POW STATE2 
PMX POST POW _STATE2 


PMX PRE POW STATE3 
PMX POST POW_STATE3 


and dwContextLossSeverityF lags is currently one of: 


PMX NO _CONTEXT_LOSS 
6 PMX SEVERE LOSS OF CONTEXT 


(the callback function has a typedef to STATE CALLBACK in kmapi.h) 


On getting the "PRE" notification, (which can be conveniently tested by anding with the 
PMX PRE STATE CHANGE MASK, defined in kmapi.h), you should wait for all of your 
asynchronous commands that depend on the display mode to complete before returning. 


In the event of getting a PMX SEVERE LOSS OF CONTEXT message at the start of a 
state change, you should preserve all your context somewhere. (for later restoring). 


6. RINGO FUNCTION & MACRO REFERENCE 


Note that many of the structures described here contain a dwStructSize field. As far as I’m 
aware, this is never used in the Kernel Manager, and consequently contains no valid 
information. It is a hangover from earlier incarnations of the system. 


6.1.1 KMLoadCodeFragment 


DWORD __ stdcall KMLoadCodeFragment(PCODE_ DETAILS); 


This function loads primary core code onto the given thread on the given device. It takes a 
pointer to the following structure, and fills out the psCodeCtIBIk field with a handle to the 
loaded thread. 


typedef struct_ CODE DETAILS _ 


eo | 
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DWORD dwStructSize; (Do not use) 
DWORD dwErrorCode; (Output) 
PDWORD pdwInfoBuffer; (Input) 
DWORD dwLoadFlags; (Set this to 0) 
DWORD dw Thread; (Input) 
PCODE CTLBLK _ psCodeCtlBlk; (Output) 


PDEVICE_CTLBLK psDeviceCtIBlk; (Input) 
} CODE_DETAILS, *PCODE_DETAILS; 


psDeviceCtIBlk is the device handle returned by KMMapOSDevCookieToDevice. 


psCodeCtIBlk is a unique identifier for the code fragment in the frame buffer. It is passed to 
KMGetSymbolHostAddress to indicate which fragment we’re looking for symbols within. 


6.1.2 KMUnloadCodeFragment 

DWORD __ stdcall KMUnloadCodeFragment(PCODE_ CTLBLK psCodeCtlBIk); 

Frees the the code fragment identified by psCodeCtIBlk. Deallocates all frame buffer and 
host memory that was allocated for it. 


t 6.1.3 KMFindThreadWithCaps 


DWORD __ stdcall KMFindThreadWithCaps(PFIND_THREAD); 


This locates a thread on a specified device having the given capabilities. It uses the following 
structure: 


typedef struct FIND THREAD _ 


{ 
DWORD dwStructSize; (Input) 
DWORD dwCaps; (Input) 
DWORD dwThreadNum; (Output) 
PDEVICE CTLBLK psDeviceCtIBlk; (Input) 
od DWORD dwErrorCode; (Output) 
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} FIND_THREAD, *PFIND_THREAD; 


You must set up the capabilities request flags by orring together the following macros: 


KM HCAPS BG -- Thread is a background thread 

KM_HCAPS 2DCORE -- Thread can use a 2D core 

KM_HCAPS RT -- Thread is real-time (obsolete) 

KM_HCAPS KERNEL 

KM HCAPS HARDRT -- Thread is hard real time (obsolete) 
7) KM HCAPS DACCORE _— -- Thread can use a DAC core 


KM HCAPS VOUTCORE -- Thread can use a video out core 
KM _HCAPS_ VINCORE _ -- Thread can use a video in core 


The function fills out the dwThreadNum with the number of a thread on the specified device 
having the desired capabilities. This number is usually passed to KMLoadCodeFragment to 


indicate which thread to load code onto. 


6.1.4 KMGetCodeCtlBlkPtr 


DWORD __ stdcall KMGetCodeCtlBIkPtr(PGET CTLBLKPTR); 


This function allows you to obtain the unique identifier for a loaded primary core code 
& fragment by specifying which device it exists on, and what its name is. 


typedef struct_ GET CTLBLKPTR_ 


{ 
DWORD dwStructSize; 
DWORD dwErrorCode; 
PSZ pszFragName; 


PDEVICE CTLBLK psDeviceCtlBlk; 
PCODE_CTLBLK _ psCodeCtl; 
} GET CTLBLKFTR, *PGET CTLBLKPTR; 
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On return, the psCodeCtl field is filled out with the handle for the requested fragment. If the 
system cannot find the requested code fragment, then dwErrorCode will be set to 
KM_ERROR_ SYMBOL NOT FOUND, otherwise it will be set to KM_OK. 


6.1.5 KMGetSymbolHostAddress 


DWORD (_ stdcall *KMGetSymbolHostAddress)( PSZ —pszName, PCODE. CTLBLE. 
psCodeCtl, PVOID *ppvAddress ); 


Given the handle to the code fragment, and the name of a symbol, this function fills out the 
ppvAddress parameter with the linear (host) address of the requested symbol. If the system 
cannot find the requested symbol, then KM ERROR SYMBOL NOT FOUND will be 
returned, otherwise KM_OK will be returned. 


6.1.6 KMGetSymbolHighAddress 


DWORD _ stdcall KMGetSymbolHighAddress( PSZ pszName, PCODE CTLBLK 
psCodeCtl, PD WORD pdwHighAddress ); 


Given the handle to the code fragment, and the name of a symbol, this function fills out the 
ppvAddress parameter with the physical address of the requested symbol. If the system 
cannot find the requested symbol, then KM ERROR SYMBOL NOT FOUND will be 
returned, otherwise KM_OK will be returned. 


6.1.7 KMMapOSDevCookieToDevice 


DWORD __stdcall KMMapOSDevCookieToDevice(D WORD dnOSDevCookie, 
PDEVICE_CTLBLK * ppsDCB); 


This function translates between the operating systems’ unique device handle and a device 
handle that the Kernel Manager understands (A PDEVICE CTLBLK). As a special case, 
passing in dnOSDevCookie = | will, when the Kernel Manager has been built with a SIM=1 
flag, return a handle for the simulated device. 


6.1.8 KMAllocStaticFBMem 


DWORD KMaAllocStaticFBMem( PDEVICE_CTLBLK psDeviceCtIBlk, DWORD dwFlags, 
DWORD dwSize, DWORD dwAlignment, PVOID *ppvLinAddr, PD WORD pdwPhysAddr 


) 
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Allocates a static block in the given devices’ frame buffer. A static block cannot be moved by 
the memory manager. 


psDeviceCtlBlk is the handle of the device whose frame buffer is to be allocated from 
dwFlags can be one of 

KM _FB GENERAL HEAP 

KM _ FB PROTECT HEAP 

KM_FB ICACHE2 HEAP 

KM_FB_TEXTURE_HEAP 

and any of these can be orred with 


KM HEAP NOT SPLIT PAGE (setting this flag will prevent a block being allocated 
across a page boundary). 


dwAlignment is the byte - alignment to allocate the block on. This must be greater than or 
equal to 8, and also must be a power of two. 


ppvLinAddr is a pointer to a PVOID which receives the linear address of the allocated block 


pdwPhysAddr is a pointern to a DWORD which receives the physical address of the 
allocated block. 


6.1.9 KMAIlocMovFBMem 


DWORD __stdcall KMAllocMovFBMem(PDEVICE CTLBLK psDeviceCtIBlk, DWORD 
dwFlags, DWORD dwSize, DWORD dwAlignment, PVOID *ppvHandle); 


Allocates a moveable memory block in the given devices frame buffer. An (unlocked) 
moveable block may be moved by the memory manager at any time. Such blocks may be 
locked and unlocked by calling KMLockMoveableBuffer and KMUnlockMoveableBuffer. 


Locking a block will prevent its relocation by the memory manager. 

psDeviceCtIBlk is the handle of the device whose frame buffer is to be allocated from 
dwF lags can be one of 

KM_FB_ GENERAL HEAP 

KM_FB PROTECT HEAP 

KM _ FB ICACHE2 HEAP 

KM_FB_ TEXTURE HEAP 


and any of these can be orred with 


24th June 1996 12 GUID003 
Version Draft A 


@ s / VidceoLogic 
Highlander Host Software 


G Nerray Ries 
Petia Ly DES AGG eS ‘ayaa 


fuoaueer(pAtiéih closepath } def 


KM HEAP NOT SPLIT PAGE (setting this flag will prevent a block being allocated 
across a page boundary). 


dwAlignment is the byte - alignment to allocate the block on. This must be greater than or 
equal to 8, and also must be a power of two. 


ppvHandle is a pointer to be filled out with a handle to the allocated block. Its only valid uses 
are to be passed to KMLockMoveableBuffer or KMFreeMovFBMem. 


6.1.10 KMFreeStaticFBMem 


& DWORD _ stdcall KMFreeStaticFB3Mem(PDEVICE CTLBLK psDeviceCtlBlk, DWORD 
dwFlags, PVOID pvLinAddr); 


Frees a block that was allocated by KMAllocStaticFBMem. 

psDeviceCtIBlk is the handle for the device in which the block was allocated. 
dwFlags indicates which heap the block was allocated in. i.e. one of: 

KM _ FB GENERAL HEAP 

KM _ FB PROTECT HEAP 

KM_FB ICACHE2 HEAP 

KM_FB_TEXTURE_HEAP 

pvLinAddr points to the block to be freed. 


6.1.11 KMFreeMovFBMem 


DWORD (_ stdcall *KMFreeMovFBMem)(PDEVICE_CTLBLK psDeviceCtlBlk, DWORD 
dwFlags, PVOID pyMemHandle); 


Frees a block that was allocated by KMAllocMovFBMem. 
psDeviceCtIBIk is the handle for the device in which the block was allocated. 
dwFlags indicates which heap the block was allocated in. 1.e. one of: 
KM _FB_ GENERAL HEAP 
KM FB PROTECT HEAP 
KM_FB ICACHE2 HEAP 
e KM_FB_ TEXTURE HEAP 
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pvMemHandle is the handle to the block to be freed. 


6.1.12 KMLockMoveableBuffer 


DWORD __ stdcall KMLockMoveableBuffer(PVOID pyMemHandle, PVOID *ppvLinAddr, 
PDWORD pdwPhysAddr); 


Locks a moveable block so it can’t be moved. 
pvMemHandle is the the handle for the block to be locked. 

_ ppvLinAddr - pointer to be filled out with the linear address of the locked block. 
pdwPhysAddr - pointer to be filled out with the physical address of the locked block. 


Note that the two returned pointers only remain valid so long as the block is locked. 


6.1.13 KMUnlockMoveableBuffer 


DWORD __stdcall KMUnlockMoveableBuffer(PVOID pyMemHandle); 


Unlocks the moveable block with the given handle. 


6.1.14 KMGetAvailMemory 


®& DWORD __stdcall KMGetAvailMemory(PAVAIL_ MEM); 


This queries the given device for the amount of free space it contains in a given heap or the 
maximum free space for full-screen DOS modes. 


Heaps are arranged as : 
Top of heap 
Static portion 
Shared Area 
Moveable portion 


Bottom of heap 


r So the static heap grows downwards, and the moveable heap grows upwards. 
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typedef struct AVAIL MEM _ 


{ 
DWORD dwStructSize; (Input) 
DWORD dwErrorCode; (Output) 
DWORD dwFlags; (Input) 
DWORD dwModeSpace; (Output) 
DWORD dwFreeInMoveable; (Output) 
DWORD dwLargestInMoveable; (Output) 
al DWORD dwLargestInStatic; (Output) 
DWORD dwFreelInStatic; (Output) 
DWORD dwCard; (Output) 


PDEVICE_CTLBLK psDeviceCtlBlk; (Input) 
} AVAIL_MEM, *PAVAIL MEM; 


dwStructSize — not used 
dwErrorCode — not used 


dwF lags — which heap to scan for free space (will usually be KM FB GENERAL HEAP). 
You can indicate (by orring in):- 


KM HEAP MODE VALIDATION — set only dwModeSpace, without bothering to 
calculate the other heap parameters. 


& KM_ HEAP COMPACT — perform a heap compaction before measuring the available space 
(very slow). 


dwModeSpace — number of bytes from the bottom of the specified heap to the bottom of the 
static portion of that heap. 


dwFreeInMoveable — total amount of free space in the moveable portion of the heap. 


dwLargestInMoveable — largest block in the moveable portion of the heap. This is the largest 
allocation size that can be guarenteed to succeed. (Although larger allocations may succeed if 
the memory manager manages to compact the memory well). 


dwLargestInStatic — as above, but this gives information on the static portion of the heap. 
dwFreeInStatic — as above, but this gives information on the static portion of the heap. 


dwCard — total SDRAM on the card (in bytes) 
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6.1.15 KMMapLinToPhys 


DWORD __ stdcall *K{MMapLinToPhys(PVOID); 


This is a utility service which simply calculates the physical address corresponding to a given 
linear address. 


6.1.16 KMAIlocComIF 


DWORD _ stdcall KMAllocComIF( PDEVICE CTLBLK  psDeviceCtlBlk, DWORD 
e dwThread, DWORD- dwFlags, PCOMMANDIF *ppsCommandIF, PDWORD 
pdwHPtrCommandIF ); 


Allocates a structure called a Command Interface which is used for sending asynchronous 
commands to the primary core. 


psDeviceCtlBlk — handle for the device on which to create the command interface 
dwThread — thread number on which to create the command interface 


dwFlags — should be 0, or KM_COMIF_ GETFIRST to get at the first command interface 
(which is otherwise reserved). For non-background threads, the reserved command interface 
is the only one supported. This means that for non-background threads, you MUST set 
KM_COMIF_ GETFIRST. 


ppsCommandIF — pointer to fill out with the address of the allocated command interface 


pdwHPtrCommandIF — pointer to a DWORD to fill out with the physical address of the 
* allocated command interface. 


6.1.17 KMFreeComlF 

DWORD _ stdcall KMFreeComIF(PCOMMANDIF psCommandIF); 

6.1.18 KMInstallVxDIntHandler 

DWORD __ stdcall KMiInstallVxDIntHandler(PDEVICE_CTLBLK psDCB, 


PINT CALLBACK pfnCallback, DWORD dwContext, DWORD dwIntMask); 


6.1.19 KMRemoveVxDIntHandler 


* DWORD _ stdcall KMRemoveVxDIntHandler(PDEVICE CTLBLK psDCB, DWORD 
dwIntMask); 
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6.1.20 KMAIllocPages 


PVOID _ stdcall KMAllocPages(DWORD dwNumPages, DWORD dwUserF lags); 
Allocates the required number of pages on the host PC, starting on a page boundary. 
dwUserF lags can be one of: 

GHEAP_BLOCK_ LOCK for locked (unpageable) pages 
GHEAP_ BLOCK _UNCACHED for uncached pages. 


6.1.21 KMFreePages 


VOID __stdcall KMFreePages( PVOID pvAddress, DWORD dwNumPages, DWORD 
dwF lags ); 


pvAddress — linear address of the pages to free. 
dwNumPages — number of pages to free 


dwF lags — currently unused 


The pvAddress and dwNumPages must be the values that were returned by a call to 
KMAllocPages. Freeing of subranges is not supported. 


6.1.22 KMGetCmndBufferInfo 


DWORD  _ stdcall KMGetCmndBufferlnfo(PDEVICE CTLBLK _ psDeviceCtlBlk, 
PCMND_BUF_INFO psGetCmndInfo); 


Retrieves information about the circular command buffer for a specified device. The returned 
structure is defined as : 


typedef struct_ CMNDBUFINFO _ 


{ 
PBYTE pbyCmndBufLinBase; -- linear base of command buffer 
DWORD dwCmndBufPhysBase; -- physical base of command buffer 
PDWORD _ pdwAccess; -- linear address of access field 
PDWORD _ pdwWoOff; -- linear address of write offset cursor 
PDWORD _ pdwROff; -- linear address of read offset cursor 
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PDWORD _ pdwkKick; -- linear address of kicker register 
DWORD dwCBInHost; -- Not Used 
} CMND_BUF_ INFO, *PCMND_BUF_INFO; 
These are all outputs, except for dwCBInHost, which is not currently used. 
6.1.23 KMSetCmndBufferInfo 
DWORD ~ _ stdceall KMSetCmndBufferlnfo(PDEVICE CTLBLK _ psDeviceCtlBlk, 
PSET_CMND_BUF_INFO psSetCmndInfo); 


This function takes a SET CMND_BUF_INFO structure of the form 


typedef struct SET CMND_BUF_INFO_ 


{ 
PDWORD _ pdwAccess; _ -- linear address of access field for this CCB 
PDWORD ~~ pdwWOff; _ -- linear address of write offset cursor 
PDWORD _ pdwROff; -- linear address of read offset cursor 


’ SET CMND BUF _INFO, *PSET CMND BUF _INFO: 


The intent is for the display driver to set these values early on. 


6.1.24 KMAllocHostMem 


DWORD _ stdcall KMAllocHostMem(DWORD dwFlags, DWORD dwSize, PVOID 
*ppvLinAddr, DWORD *pdwPhysAddr); 


Allocates memory on one of the host heaps. The heap can be chosen by setting the dwFlags 
word to be one of : 


KM HOST PAGEABLE_HEAP 
KM HOST NON PAGEABLE_HEAP 
KM HOST _NON_CACHED_ HEAP 


The function will return an error code if it fails, or KM_OK if it succeeds. 
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6.1.25 KMFreeHostMem 


DWORD __ stdcall KMFreeHostWem(DWORD dwFlags, PVOID pvLinAddr); 


Frees a block of memory in the specified heap, given the linear address of the block. 


dwF lags must be set to the heap from which the block was originally allocated. 


6.1.26 KMWriteOBC 
DWORD _ stdcall *KMWriteOBC(PDEVICE CTLBLK psDCB, DWORD dwCount, 
PWORD pwReg, PWORD pwData); 


This function is not applicable to PMX2 


Writes several values to a PMX devices’ out-of-band control registers. 


psDCB — handle of the device to write to 

dwCount — number of registers to write to 

pwReg — array of 16-bit words containing the numbers of the registers to write to 
pwData — array of 16-bit words containing the values to write into the corresponding 
registers 


6.1.27 KMReadOBC 
DWORD _ stdcall _KMReadOBC(PDEVICE CTLBLK psDCB, DWORD dwCount, 
PWORD pwReg, PWORD pwData); 


This function is not applicable to PMX2 


Reads several values from a PMX devices’ out-of-band control registers. 


psDCB — handle of the device to read from 

dwCount — number of registers to read from 

pwReg — array of 16-bit words containing the numbers of the registers to read from 
pwData — array of 16-bit words containing the read from the corresponding registers 
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6.1.28 KMWriteOBCAI 


DWORD _ stdcall KMWriteOBCAI(PDEVICE CTLBLK psDCB, DWORD dwCount, 
DWORD wlReg, WORD wlIData, WORD wDReg, PWORD pwData); 


This function is not applicable to PMX2 


Writes dwCount auto incrementing data values to OBC via SPAM. 


psDCB -- identifier for this device 

dwCount -- count of data values to write to data reg 

wlReg -- auto incrementing index register address 

wlData -- seed value for ai index reg. 

wDReg -- data register address 

pwData -- (16-bit) word array of data to write to data register. 


6.1.29 KMReadOBCAI 


DWORD _ stdcall KMReadOBCAI(PDEVICE CTLBLK psDCB, DWORD dwCount, 
WORD wiReg, WORD wlIData, WORD wDReg, PWORD pwData); 


This function is not applicable to PMX2 


Reads dwCount auto incremented data values from OBC via SPAM. 


psDCB -- identifier for this device 

dwCount -- count of regs to read 

wlReg -- auto incrementing index register address 
wlData -- seed value for ai index reg. 

wDReg -- data register address 

pwData -- word array of data to read from data register. 


6.1.30 KMReadOBCNB 


DWORD _ stdcall KMReadOBCNB(PDEVICE CTLBLK psDCB, DWORD dwCount, 
PWORD pwReg, PWORD pwData); 


This function is not applicable to PMX2 
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As for KMReadOBC, except that if another read is being carried out on the same device, this 
returns straightaway with the error KM ERROR RESOURCE INUSE. 


It is intended to be called from inside an interrupt routine. 


6.1.31 KMGetCardInfo 


DWORD _ stdcall KMGetCardInfo(PDEVICE CTLBLK psDCB, PKMCARDINFO 
psInfo); 


Fills out the passed in structure with various bits of information about the specified device. 


The structures involved are: 


typedef struct KMCARDINFO _ 


{ 
DWORD dwStructSize; 
DWORD dwErrorCode; 
DEV_PCI sPCl: -- PCI config information 
DEV_ LOCATION — sMem; -- Memory information 
PDEVICE CTLBLK psDeviceCtlBlk; 

} 


KMCARDINEFO, *PKMCARDINFO; 


typedef struct _ DEV PCI_ 


{ 
DWORD dwBus; --Bus for this device 
DWORD dwSlot; --Slot for this device 
DWORD dwFunc; --Function for this device 
DWORD dwHWRevy; --Hardware revision (1 = PMX1C, 2 = PMXLC) 
DWORD dwIRQ; 
DWORD dwDevicelD; 
DWORD dwVendorID; 
DWORD dwSubSysID; 

a DWORD dwSubSysVendorlD; 
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DWORD dwBIOSRev; 


DWORD dwBoardRev; --This is defunct - don't use 
DWORD dwIsAGPCard; --1 if this is an AGP card 

} 

DEV_ PCI; 


typedef struct_ DEV LOCATION _ 


{ 
DWORD dwF BPhysicalBase; -- Physical base of frame buffer 
DWORD dwFBLinearBase; -- Linear base of frame buffer 
DWORD dwFBMemorySize; -- Size of frame buffer memory 
DWORD dwSysRegsPhysBase; -- Physical base of registers 
DWORD dwSysRegsLinBase; -- Linear base of registers 


DWORD dwComsRegsPhysBase; 
DWORD dwComsRegsLinBase; 


DWORD dwROMPhysicalBase; -- Physical base of ROM 
DWORD dwROMLinearBase; -- Linear base of ROM 
DWORD dwROMSize; -- Size of ROM (bytes) 
DWORD dwATLUTRegionBase; -- Deprecated. Do not use. 


} DEV_LOCATION; 


6.1.32 KMAIlocHostCacheCoherentHeap 


DWORD  _ stdcall KMAIlocHostCacheCoherentHeap(PDEVICE CTLBLK  psDCB, 
DWORD- dwSize, DWORD  dwAlignment, PVOID  *ppvLinAddr, _DWORD 
*pdwPMXAddr); 


Allocates host memory which is guarenteed to be cache coherent with the PMX device. If the 
PMxX device reads from this region, then it is guarenteed to flush the host’s caches in order to 
provide the data. Note that general reads from host memory will not usually be cache 
coherent (i.e. they won’t take any notice of what is in the processors cache). 
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6.1.33 KMFreeHostCacheCoherentHeap 


DWORD (_stdcall *KMFreeHostCacheCoherentHeap)(PDEVICE CTLBLK psDCB, 
PVOID pvLinAddr); 


Frees memory allocated in the cache coherent heap of the specified device. 


6.1.34 KMPower 


DWORD __stdcall KMPower(PDEVICE_CTLBLK psDCB, DWORD dwFlags, PDWORD 
. pdwState); 


Notifies the Kernel manager of a power mode change on a particular device, or reads the 
current power mode. 


dwF lags -- indicates whether we’re setting or getting a state 
KM POW_GETSTATE 
KM _POW_SETSTATE 


pdwState -- pointer to a DWORD to receive or supply the state value 
this value will be one of: 

KM _POW_STATEO -- Running full speed 

KM POW _STATEI -- Not currently supported 

KM_POW_STATE2 -- Not currently supported 


KM POW_STATE3 -- Device power off state 


6.1.35 KMCorePLL 


DWORD _ stdcall KMCorePLL(PDEVICE CTLBLK psDCB, DWORD_ dwFlags, 
PDWORD pdwFreq); 


Sets or gets the core PLL frequency of the specified device. 
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dwF lags is one of: 
KM_CORE PLL SET 
KM_CORE PLL_GET 


pdwFreq points to a DWORD which receives or supplies the the clock frequency in MHz. 


6.1.36 KMState 


DWORD __stdcall KMState(PDEVICE CTLBLK psDCB, DWORD dwState); 


Notifies the Kernel Manager of a state change. This will typically call a callback on 
components which have registered with the Kernel Manager to receive state change 
notifications. (see KMRegisterStateChangeCallback below). 


dwState is one of: 

PMX_ PRE WINDOWS MODE CHANGE 
PMX PRE HIREZ TO VGA 

PMX _POST_HIREZ TO VGA 

PMX PRE VGA_TO_HIREZ 

PMX POST _VGA_TO_HIREZ 


PMX PRE XY REZ CHANGE 
PMX POST XY REZ CHANGE 
PMX PRE Z REZ CHANGE 
PMX POST_Z REZ CHANGE 


6.1.37 KMGetAPITable 


DWORD _ stdcall KMGetAPITable( PCODE CTLBLK  psCodeCtlIBlk, PDWORD 
*ppdwAP!ITable ); 


Fills out the PDWORD pointed to by ppdwAPITable with the linear address of the API table 
for the given code fragment. No device handle is necessary, as the code control block 
implicitly specifies a device anyway. 
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6.1.38 KMRegisterStateChangeCallback 


DWORD _ stdcall KMRegisterStateChangeCallback( PDEVICE_CTLBLK psDeviceCtlBlk, 
PSTATE CALLBACK pfnCallback ); 


Registers a callback with the kernel manager to be called when the power mode changes, or 
when we receive a DOS box pre or post mode change message. 


The callback function should be of the form: 


Fn( PDEVICE CTLBLK  psDeviceCtlIBlk,  DWORD  dwStateFlags, DWORD 
dwContextLossSeverityFlags ) 


Be sure to use the _ stdcall declaration in defining your callback. Casting to a __stdcall type 
is not sufficient. 


6.1.39 KMDeRegisterStateChangeCallback 


DWORD __ stdcall KMDeRegisterStateChangeCallback( PDEVICE CTLBLK 
psDeviceCtlBIk, PSTATE_ CALLBACK pfnCallback ) 


Removes a state change callback from the list of handlers 


6.1.40 KMEnableDevice 


DWORD __ stdcall KMEnableDevice( PDEVICE_CTLBLK psDCB ) 


Initialises the heaps, etc. and starts the chip running in Windows (non-VGA) mode for a 
particular device. No other device-specific call may be made before _ this. 
(KMMapOSDevCookie is OK, obviously). 


7. DEVICEIOCONTROLINTERFACE REFERENCE 


This interface allows ring3 applications to access the Kernel Manager, by using an IOCTL 
(win9x only). It is used for testing. 


The format of these calls is: 


DeviceIoControl( hVxd, KM FUNCTION NUMBER, &sInOut, sizeof ( 
KM FUNCTION STRUCTURE hy &SInOut, sizeof ( 
KM FUNCTION STRUCTURE ), &dwBytesReturned, NULL )); 
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where 


hVxd is a handle to the Kernel Manager VxD 


KM_ FUNCTION NUMBER is a number indicating which function to call (specified in 
kmapi.h) 


KM FUNCTION STRUCTURE is the type of structure demanded by the function being 
called. This holds all input/output parameters. 


sInOut is the structure (of type KM FUNCTION STRUCTURE) containing the parameters 
of the call. This contains a dwErrorCode field, so that all functions can indicate an error code. 


The following functions are currently supported, in almost every case they behave exactly as 
the corresponding KM function. Only the exceptions are described in detail. 
7.1.1 KM_API LOAD CODEFRAGMENT 


Uses CODE_DETAILS structure as the interface 
typedef struct CODE DETAILS _ 


{ 
DWORD dwStructSize; (Do not use) 
DWORD dwErrorCode; (Output) 
PDWORD | pdwInfoBuffer; (Input) 
DWORD dwLoadFlags; (Input — should be 0) 
DWORD dwThread; (Input) 
PCODE_CTLBLK _ psCodeCtlBlk; (Output) 


PDEVICE_CTLBLK psDeviceCtlBlk; (Input) 
} CODE_DETAILS, *PCODE_ DETAILS; 


7.1.2 KM API UNLOAD CODEFRAGMENT 


Unloads a code fragment. Uses a CODE_DETAILS structure as the interface. 


7.1.3 KM_API_ FIND THREAD WITH CAPS 


Uses a FIND_THREAD structure as the interface 
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7.1.4 KM _API_ GET _CODECTLBLOCKPTR 


Uses the following structure as the interface: 


typedef struct GET CTLBLKPTR_ 


t 
DWORD dwStructSize; (Do not use) 
DWORD dwErrorCode; (Output) 
PSZ pszFragName; (Input) 
PDEVICE CTLBLK psDeviceCtlBlk; (Input) 
| ) PCODE CTLBLK _ psCodeCtl; (Output) 


} GET _CTLBLKPTR,*PGET CTLBLKPTR; 


7.1.45 KM_API_GET_ SYMBOL_ADDRESS 


Uses the following structure as the interface: 


typedef struct GET SYMBOL ADDR _ 


{ 
DWORD dwStructSize; 
DWORD dwErrorCode; 
PSZ pszName; 
PCODE_CTLBLK _ psCodeCtl; 
& DWORD dwHighAddress; 
PVOID pvHostAddress; 


} GET_SYMBOL_ ADDR, *PGET SYMBOL ADDR; 


This is different from the ringO function in that here we have a single call that returns both 
linear and physical addresses of the specified symbol. 
7.1.6 KM_API_ GET _API_TABLE 


Uses the following structure as the interface: 


typedef struct GET API TABLE _ 


{ 
o DWORD dwStructSize; 
DWORD dwErrorCode; 
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PCODE CTLBLK _ psCodeCtIBlk; 
PDWORD pdwAPITable; 
} GET_API_TABLE, *PGET_API_ TABLE; 


7.1.7 KM_APIL MAP OSDEVCOOKIE_TO_DEVICE 


Uses the following structure as the interface: 


typedef struct MAP OSDEVCOOKIE _ 
{ 


DWORD dwStructSize; 
DWORD dwErrorCode; 
DWORD sOSDevCookie; 


PDEVICE CTLBLK psDeviceCtlBlk; 
} MAP_OSDEVCOOKIE, *PMAP_OSDEVCOOKIE; 


7.1.8 KM_API_GET_ CARD INFO 


Uses the following structure as the interface: 


typedef struct KMCARDINFO _ 
{ 


DWORD dwStructSize; 
DWORD dwErrorCode; 
DEV_PCI SPC; 


DEV_ LOCATION = sMem; 
PDEVICE CTLBLK psDeviceCtlBlk; 


} 
KMCARDINFO, *PKMCARDINFO; 


See KMGetCardInfo for more information on the DEV PCI and DEV LOCATION 
structures. 


7.1.9 KM_API LOCK MOVEABLE BUFFER 
Uses the following structure as the interface: 
typedef struct MOVE LOCK UNLOCK __ 

{ 
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DWORD dwStructSize; 
DWORD dwErrorCode; 
PVOID pvHandle; 
PVOID pvHostAddress; 
DWORD dwHighAddress; 
} MOVE LOCK UNLOCK, *PMOVE LOCK UNLOCK; 


This will lock the block with the specified handle, and write the linear and physical addresses 
of the locked block into pyHostAddress and dwHighAddress. 


7.1.10 KM API_UNLOCK MOVEABLE BUFFER 
This uses the MOVE LOCK UNLOCK structure, but it ignores the pvHostAddress and 
dwHighAddress fields. 


It unlocks the moveable block with the specified pvHandle. 


7.1.11 KM API MAP LIN _TO PHYS 


This uses the following structure: 
typedef struct_ MAP LIN TO PHYS _ 
{ 
DWORD dwStructSize; 
DWORD dwErrorCode; 
DWORD dwLinAddr; (Input) 
DWORD dwPhysAddr; (Output) 
} MAP_LIN_TO_ PHYS, *PMAP LIN TO PHYS; 


Given a linear address dwLinAddr, this finds the corresponding physical address, and returns 
it in dwPhysAddr. 


7.1.12 KM_API ALLOC_STATIC_FB MEMORY 


This uses the following structure: 


typedef struct STATIC _ALLOC_ 
{ 
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DWORD dwStructSize; 
DWORD dwErrorCode; 
DWORD dwSize; 
DWORD dwLocation; 
PVOID pvHostAddress; 
DWORD dwHighAddress; 


PDEVICE_CTLBLK psDeviceCtlBlk; 
} STATIC_ALLOC, *PSTATIC_ALLOC; 
dwLocation should be set to the same set of flags as in KMAIlocStaticFBMem 


7.1.13 KM_API_FREE_STATIC_FB_MEMORY 


This uses the structure below: 


typedef struct STATIC FREE _ 
{ 


DWORD dwStructSize; 
DWORD dwErrorCode; 
PVOID pvAddr; 
DWORD dwLocation; 


PDEVICE CTLBLK psDeviceCtIBlk; 
} STATIC_FREE, *PSTATIC_FREE; 


Again, dwLocation must be one of the region flags used in KMAllocStaticFBMem. 
pvAddr is the linear address returned by KM_API_ALLOC_STATIC_FB_ MEM 


7.1.14 KM API GET_AVAILABLE_MEMORY 


This uses an AVAIL_ MEM structure as the interface. 


7.1.15 KM_APIL ALLOC_MOV_FB_ MEMORY 


This takes a MOVE _ALLOC structure: 
typedef struct MOVE ALLOC_ 


{ 
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DWORD dwStructSize; 
DWORD dwErrorCode; 
DWORD dwSize; 
DWORD dwLocation; 
PVOID pvHandle; 


PDEVICE CTLBLK psDeviceCtlBlk; 
} MOVE_ALLOC, *PMOVE_ ALLOC; 


@ pvHandle is a handle to the (unlocked) moveable block. 


dwLocation is one of the standard set of frame buffer allocation flags. 


7.1.16 KM_API_ FREE MOV_FB_ MEMORY 


This uses the following structure as its interface 


typedef struct MOVE FREE _ 


{ 
DWORD dwStructSize; 
DWORD dwErrorCode; 
PDEVICE CTLBLK psDeviceCtIBlk; 
DWORD dwLocation; 
|) PVOID pvHandle; 


} MOVE FREE, *PMOVE FREE; 


psDeviceCtIBlk and dwLocation should be set up as they were for the allocation of the block. 
pvHandle should be the value returned from KM_API_ ALLOC_MOV_FB MEMORY 


7.1.17 KM_API ALLOC_ HOST MEMORY 

This uses a STATIC_ALLOC structure in its interface, except that the dwLocation field 
should be set to one of the host heap location flags: 

KM_ HOST PAGEABLE HEAP 

KM_HOST_ NON PAGEABLE HEAP 

KM HOST NON CACHED HEAP 
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7.1.18 KM_API_ FREE HOST MEMORY 


This takes a STATIC_FREE structure, with the dwLocation field being one of the host heap 
location flags. 


7.1.19 KM_GET SERVICE TABLE 


This takes the following structure, which it fills out with the relevent data 
typedef struct agK{MSERVICE 
{ 
DWORD dwNumServices; 
PKM SERVICE TABLE _psService; 
} 
KMSERVICE, *PKMSERVICE; 
the definition of a KM SERVICE TABLE is given in kmapi.h p — it includes all the ringO 


functions. 
7.1.20 KM_API ALLOC_COMIF 


This uses the following structure: 


typedef struct ALLOC_CMDIF _ 


{ 
DWORD dwStructSize; 
DWORD dwErrorCode; 
DWORD dwThread; (Input) 
DWORD dwF lags; (must be zero) 
PCOMMANDIF psCommandIlF; 
DWORD dwHPtrCommandIF; 


PDEVICE_CTLBLK psDeviceCtIBIk; 
} ALLOC_CMDIF, *PALLOC_CMDIF; 


Given a thread number and a device handle, this allocates a command interface for that 
thread. It returns the linear address of the allocated command interface (in psCommandIF) as 
well as its physical address (in dwHPtrCommandIF) 
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7.1.21 KM_API_FREE_COMIF 


This takes the same ALLOC_CMDIF structure as KM_API_ ALLOC_COMIF. It ignores all 
fields except the linear and physical address of the command interface 
7.1.22 KM_API_ SET_CMND BUF_INFO 


This uses the following structure (CCB refers to the circular command buffer) 


typedef struct_ DIOC_CMND_ BUF _ INFO _ 


{ 
PDEVICE_CTLBLK psDeviceCtlBlk; 
PBYTE pbyCmndBufLinBase; -- (Ignored) 
DWORD dwCmndBufPhysBase; -- (Ignored) 
PDWORD pdwAccess; -- (Input) Linear address of access flag 
PDWORD pdwW Off; -- (Input) Linear address of Woff cursor 
PDWORD pdwROff; -- (Input) Linear address of Roff cursor 
PDWORD pdwKick; -- (Output) Address of kicker 
DWORD dwCBInHost; -- Not used 


. DIOC_CMND_ BUF INFO, *PDIOC_CMND BUF _INFO; 


7.1.23 KM_API_GET_CMND_BUF_INFO 


This uses the same DIOC_CMND_ BUF_INFO structure as 
KM_ API SET CMND_ BUF INFO, although it is interpreted differently. 


typedef struct_ DIOC_CMND_BUF_INFO_ 


{ 
PDEVICE CTLBLK psDeviceCtIBlk; 
PBYTE pbyCmndBufLinBase; -- (Output) linear base of CCB 
DWORD dwCmndBufPhysBase; -- (Output) physical base of CCB 
PDWORD pdwAccess; --(Output) Linear address of access flag 
PDWORD pdwW Off; --(Output) Linear address of Woff cursor 
PDWORD pdwROff; --(Output) Linear address of Roff cursor 
PDWORD pdwkKick; --(Output) Address of kicker 
DWORD dwCBInHost; --Not used 


. DIOC_CMND BUF INFO, *PDIOC_CMND BUF INFO: 
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8. MACROS 


8.1.1 FENCED WRITE( dwAddr, dwData ) 


Performs a fenced write of the given DWORD to the given (linear) address. The means that 
the processor will flush all outstanding writes in its write buffer before starting this fenced 
write. It is therefore used to enforce in-order writes to memory on systems with write- 
combining. 


8.1.2 CMND BUFFER SIZE 


Defines the size of the circular command buffer, in bytes. 


8.1.3 CMND BUFFER OVERFLOW 


Defines the size of the circular command buffer overflow area, in bytes. 


8.1.4 GET_PCCB_SPACE(WOff,ROff) 


Given (de-referenced) Woff and Roff cursors, this will return the amount of space (in bytes) 
currently in the circular command buffer. 


8.1.5 UPDATE_PCCB_WOFF(USize,WOff) 


Given a size in bytes, and a (de-referenced) Woff cursor, this will modify the Woff to point to 
the next free item in the circular command buffer. Usize must be a multiple of the current 
primary core cache line size (currently 64 bytes). 


8.1.6 CalcParamSize 


__ inline DWORD CalcParamSizeCCB(DWORD dwParamSize) ; 


Returns the input ParamSize, rounded up to a multiple of 64. 


8.1.7 ReleaseCCB 


__ inline void ReleaseCCB(PCMND_BUF_INFO psPCCB); 
Frees the CCB by zeroing its dwAccess field 
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8.1.8 GetCCB 


Waits for CCB access rights and checks for available space in CCB for blit param structure 


__ inline PVOID GetCCB(PCMND_BUF_INFO psPCCB, DWORD dwParamSize); 


psPCCB -- pointer to CCB information struct 


dwParamSize -- size of blit data structure 


Returns the new address of next free slot to write to if successful, else returns 0 


9, SIMULATION BUILDS OF THE KERNEL MANAGER 


For running software primary core / secondary core simulations, a special build of the kernel 
manager (build flag SIM=1) is required. This build will then obtain the following 
information from the registry on startup: 


\HKEY_ LOCAL _MACHINE\SOFTWARE\VideoLogic\PMXSIM 


FreeCommandIFs String if 0 then command interfaces will never be 
freed by KMFreeComIFs. This setting is used 
for the generation of hardware simulation data. 


SimCardMemorySize String Amount of memory on the simulated card 
SimHardwareVersion String 1 for PMX1 2 for LC, 3 for PMX2 
SimPhysicalBase String Physical Base of the simulated frame buffer 
SimTextureMemory Offset String Offset into the frame buffer at which to start 


texture memory 


FreeCommandIFs String Indicates whether we should free command 
interfaces when asked to do so, or allow them 
to build up in memory (used for hardware 
sims). For normal operation this will be set to 
“0x00000000” 


ah Values stored as strings in the registry are interpreted as hex strings if you prefix them with 
“Ox”. In fact no other interpretation is currently permitted. 
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